feat(accounts)!: enforce change feed changed_paths and per-reader idempotency_key (#1647) - #1805

Spec

AdCP 3.3 (core/account-change.json), for sellers declaring the experimental account.change_feed:

• Records whose origin.kind is adcp or seller_operator MUST carry non-empty changed_paths (RFC 6901 pointers; "" for a whole-resource create, delete or purge).
• idempotency_key is echoed only on adcp records, and only to the principal that sent the originating request. Every other reader gets the record without it, and account.change_recorded notifications MUST NOT carry it.
• Creatives may carry seller_revision on list_creatives; a creative change record's resource_revision mirrors it.

The Scope3 ESA already sends changed_paths; the SDK now matches and enforces it.

Design

New module adcp.account_change_feed (its own public address; not added to the adcp top-level facade, so the API snapshot is unchanged):

Responses (list_account_changes). create_tool_caller serves both MCP and A2A. Right after the handler returns, while attribution is still on the model instances, it projects the page for the caller (ToolContext.tenant_id + caller_identity). Projection runs before model_dump, context echo, the response enhancer and version conversion.

• An adcp record attributed to the caller keeps idempotency_key. Every other record loses it: plain dicts, unattributed models, records with a different principal or tenant, and anonymous callers. If the SDK can't show the reader is the originator, the key is stripped.
• A non-adcp record carrying a key has it dropped, not refused.
• An adcp / seller_operator record without changed_paths refuses the page with VALIDATION_ERROR (field /changes/N/changed_paths, details.side = "response") and an error log on the server. This applies in every validation mode, for handlers whose application version is 3.3 or later. A handler pinned to 3.2, where changed_paths is optional, isn't checked.
• Why refuse rather than log: strict response validation is already the default and refuses these pages, because the bundled 3.3 schema encodes the rule as if/then. The SDK check makes that refusal deterministic and points at the exact field. A buyer reconciles its cache from changed_paths, so a record without it is worse than a failed read: the buyer would retry a failed read, but would silently mis-reconcile from a bad record. The feed is an experimental 3.3-only surface with no SDK 9 adopters, and the one known adopter (ESA) already conforms.

Notifications. WebhookSender.prepare_account_change_recorded / send_account_change_recorded now also accept the change record itself, plus subscriber_id= (required) and through_cursor=. A record is detected by origin / repair, which the notification schema forbids. When given a record, the SDK:

• refuses it if it breaks the rules (AccountChangeRecordError);
• builds the body via account_change_recorded_payload, which never copies the record's idempotency_key;
• uses the explicit delivery key if given, otherwise mints a fresh one, and refuses a delivery key equal to the originating request's key.

Notification-shaped payloads pass through unchanged. Their idempotency_key is the delivery key, which the SDK can't tell apart from a copied request key; the docstring warns against copying one. _notification_envelope.py needed no change.

seller_revision. It already passes through list_creatives unharmed: the model round-trips it, and server serialization at 3.3 keeps it. For buyers below 3.3, the existing 3.3 → 3.2 conversion drops it and records the loss. The same conversion drops a record's idempotency_key for 3.2 buyers. Tests pin both behaviors. The stable_creative_ids / platform_id work (#1638) is untouched.

Tests

tests/test_account_change_feed.py (41 tests):

• pointer escaping
• record rules, cross-checked against the bundled 3.3 schema
• attribution stays off the wire
• the per-reader echo matrix (same principal, other principal, tenant mismatch, anonymous, unattributed)
• dispatch through create_tool_caller with model and dict responses under strict validation
• refusal under strict validation and with validation disabled
• a 3.2-pinned handler
• notification preparation from records (fresh key, key reuse refused, missing subscriber_id, non-conformant record)
• seller_revision passthrough at 3.3 and its drop at 3.2
• mirror_creative_revision

Docs

• docs/adcp-3.3-sdk-inventory.md: the list_creatives seller_revision row and the account-change.json row are marked done.
• MIGRATION_v9_to_v10.md: new row covering refused pages, stripped keys and the record-accepting notification preparation.

Closes #1647

BREAKING CHANGE: a list_account_changes page with an adcp or seller_operator record that lacks a non-empty changed_paths is refused with VALIDATION_ERROR, and idempotency_key is stripped from every record not served to its originating principal; see MIGRATION_v9_to_v10.md.

🤖 Generated with Claude Code